﻿<?xml version="1.0" encoding="utf-8"?>
<developerOrientationDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">

  <content>
  	<para><ui>Adding controls on top of the glass:</ui> There are currently three controls supported by
  		the AeroGlassProvider:</para>
  	
  	<list class="bullet">
		<listItem><codeInline>Label</codeInline>: the standard .NET control to display text.</listItem>
  		<listItem><codeInline>PictureBox</codeInline>: the standard .NET control to display images.</listItem>
  		<listItem><codeInline>DevExpress.XtraEditors.LabelControl</codeInline>: Since I use Developer Express
  			controls, this DevExpress control can optionally be compiled into the AeroGlassProvider.</listItem>
  	</list>


  	<mediaLink>
		<caption>Control properties</caption>
		<image placement="center" xlink:href="d23e1e19-2642-47d1-b0e8-9f8b7d7a827d"/>
	</mediaLink>

    <para>Each of these controls is extended with the following properties:</para>

  	<list class="bullet">
  		<listItem><codeInline>GlassTextGlowSize</codeInline>: Gets or sets the glass text glow 
  			size. The higher the number the larger and more diffused the background glow will be
  			behind the text.</listItem>
  		<listItem><codeInline>IsRendered</codeInline>: Gets or sets a value indicating whether
  			the control should be rendered onto the glass surface. If IsRendered is set to
  			<codeInline>true</codeInline> then the control will be set to invisible and will
  			be painted onto the glass surface. If IsRendered is set to <codeInline>false</codeInline>
  			the control background will be set to <codeInline>Color.Black</codeInline> and the
  			control is allowed to function as normal.</listItem>
  		<listItem><codeInline>OnGlass</codeInline>: Gets or sets a value indicating 
  			whether the control is located on the glass. Set <codeInline>OnGlass</codeInline> to 
  			<codeInline>true</codeInline> if the control is considered to be on the glass; otherwise, 
  			set it to <codeInline>false</codeInline>.</listItem>
  	</list>
  	
  	<para>When the form <codeInline>GlassEnabled</codeInline> property is set to <codeInline>true</codeInline>
  		and a control is marked as being on the glass then the control will be painted directly onto the
  		form. The control <codeInline>Visible</codeInline> property is set to false and the
  		control <codeInline>BackColor</codeInline> is set to black. This allows the text or 
  		image to be painted properly onto the glass.</para>
  	
  	<para>The controls that are marked as being on the glass and <codeInline>IsRendered=true</codeInline>
  		will be drawn in Z-Order from back to front. You must check the running form to ensure that
  		controls that may overlap are being	drawn in the correct order. If not, then use the SendToBack
  		or BringToFront commands in	Visual Studio to rearrange the Z-Order of the controls. If you happen
  		to change the Z-Order of controls at runtime you can use the <codeInline>AeroGlassProvider.ResetZOrder</codeInline>
  		method to reset the order the controls are drawn onto the glass.</para>
 
	<alert class="warning"><para>When the glow is place behind the text a larger rectangle then the control
		bounds is required to handle the background glow. If this rectangle extends outside of the glassed
		area, it will paint the non-glassed form background to black. You must ensure that the expanded rectangle
		falls completely within the glassed area.</para></alert>
    
	<alert class="warning"><para>A rendered control which is located within the top margin can be clicked on and
		the form moved if the form property GlassTopMovesForm is set to <c>true</c>. If the control is not
		rendered, a click on the control will not be passed to the form and cannot be used with
		GlassTopMovesForm.</para></alert>

  	<alert class="warning"><para>To reduce the amount of flashing on form repaint no attempt is made to
  		clear the background where the controls are painted onto the form. This may result in display artifacts
  		if the form size is reduced smaller than the glassed area. You should constrain the form size to prevent
  		users from resizing the form to an area smaller than the glassed in area.</para></alert>
  	<alert class="warning"><para>Multi-line and wordwrapped Labels are not supported.</para></alert>
  	<alert class="note"><para>Since a Form is a Control descendent, <codeInline>OnGlass</codeInline>
  	    and <codeInline>GlassTextGlowSize</codeInline> will appear in the Forms properties.
  	    They may be set but will have no affect on the Form behavior.</para></alert>
  </content>
</developerOrientationDocument>
